<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.5"/>
<title>NDK Programmer&#39;s Guide: Stable APIs</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">NDK Programmer&#39;s Guide
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.5 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;"
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('md_3__key__topics__libraries__s_t_a_b_l_e-_a_p_i_s.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">Stable APIs </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This is the list of stable APIs/ABIs exposed by the Android NDK.</p>
<h2>Purpose</h2>
<p>Each API corresponds to a set of headers files, and a shared library file that contains the corresponding implementation, and which must be linked against by your native code.</p>
<p>For example, to use system library "Foo", you would include a header like &lt;foo.h&gt; in your code, then tell the build system that your native module needs to link to /system/lib/libfoo.so at load-time by adding the following line to your Android.mk file:</p>
<p>LOCAL_LDLIBS := -lfoo</p>
<p>Note that the build system automatically links the C library, the Math library and the C++ support library to your native code, there is no need to list them in a LOCAL_LDLIBS line.</p>
<p>There are several "API Levels" defined. Each API level corresponds to a given Android system platform release. The following levels are currently supported: </p>
<pre class="fragment">  android-3      -&gt; Official Android 1.5 system images
  android-4      -&gt; Official Android 1.6 system images
  android-5      -&gt; Official Android 2.0 system images
  android-6      -&gt; Official Android 2.0.1 system images
  android-7      -&gt; Official Android 2.1 system images
  android-8      -&gt; Official Android 2.2 system images
  android-9      -&gt; Official Android 2.3 system images
  android-14     -&gt; Official Android 4.0 system images
  android-18     -&gt; Official Android 4.3 system images
</pre><p>Note that android-6 and android-7 are the same as android-5 for the NDK, i.e. they provide exactly the same native ABIs!</p>
<p>IMPORTANT<br/>
 The headers corresponding to a given API level are now located under <code>$NDK/platforms/android-&lt;level&gt;/arch-arm/usr/include</code></p>
<h2>Android-3 Stable Native APIs</h2>
<p>All the APIs listed below are available for developing native code that runs on Android 1.5 system images and above.</p>
<h3>The C Library</h3>
<p>The C library headers, as they are defined on Android 1.5 are available through their standard names (&lt;stdlib.h&gt;, &lt;stdio.h&gt;, etc...). If one header is not there at build time, it's because its implementation is not available on a 1.5 system image.</p>
<p>The build system automatically links your native modules to the C library, you don't need to add it to LOCAL_LDLIBS.</p>
<p>Note that the Android C library includes support for pthread (&lt;pthread.h&gt;), so "LOCAL_LIBS := -lpthread" is not needed. The same is true for real-time extensions (-lrt on typical Linux distributions).</p>
<pre class="fragment">** VERY IMPORTANT NOTE: ******************************************************
*
*  The kernel-specific headers in &lt;linux/...&gt; and &lt;asm/...&gt; are not considered
*  stable at this point. Avoid including them directly because some of them
*  are likely to change in future releases of the platform. This is especially
*  true for anything related to specific hardware definitions.
*
******************************************************************************
</pre><h3>The Math Library</h3>
<p><code>&lt;math.h&gt;</code> is available, and the math library is automatically linked to your native modules at build time, so there is no need to list "`-lm`" through LOCAL_LDLIBS.</p>
<h3>C++ Library</h3>
<p>An <em>extremely</em> minimal C++ support API is available. For Android 1.5, this is currently limited to the following headers: </p>
<pre class="fragment">    &lt;cstddef&gt;
    &lt;new&gt;
    &lt;utility&gt;
    &lt;stl_pair.h&gt;
</pre><p>They may not contain all definitions required by the standard. Notably, support for C++ exceptions and RTTI is not available with Android 1.5 system images.</p>
<p>The C++ support library (-lstdc++) is automatically linked to your native modules too, so there is no need to list it through LOCAL_LDLIBS</p>
<h3>Android-specific Log Support</h3>
<p><code>&lt;android/log.h&gt;</code> contains various definitions that can be used to send log messages to the kernel from your native code. Please have a look at its content in (<code>platforms/android-3/arch-arm/usr/include/android/log.h</code>), which contain many informative comments on how to use it.</p>
<p>You should be able to write helpful wrapper macros for your own usage to access this facility.</p>
<p>If you use it, your native module should link to /system/lib/liblog.so with: </p>
<pre class="fragment">    LOCAL_LDLIBS := -llog
</pre><h3>ZLib Compression Library</h3>
<p><code>&lt;zlib.h&gt;</code> and <code>&lt;zconf.h&gt;</code> are available and can be used to use the ZLib compression library. Documentation for it is at the ZLib page:</p>
<p><a href="http://www.zlib.net/manual.html">http://www.zlib.net/manual.html</a></p>
<p>If you use it, your native module should link to /system/lib/libz.so with: </p>
<pre class="fragment">  LOCAL_LDLIBS := -lz
</pre><h3>Dynamic Linker Library</h3>
<p><code>&lt;dlfcn.h&gt;</code> is available and can be used to use the dlopen()/dlsym()/dlclose() functions provided by the Android dynamic linker. You will need to link against /system/lib/libdl.so with: </p>
<pre class="fragment">  LOCAL_LDLIBS := -ldl
</pre><h2>Android-4 Stable Native APIs</h2>
<p>All the APIs listed below are available for developing native code that runs on Android 1.6 system images and above,</p>
<h3>The OpenGL ES 1.x Library</h3>
<p>The standard OpenGL ES headers <code>&lt;GLES/gl.h&gt;</code> and <code>&lt;GLES/glext.h&gt;</code> contain the declarations needed to perform OpenGL ES 1.x rendering calls from native code.</p>
<p>If you use them, your native module should link to /system/lib/libGLESv1_CM.so as in: </p>
<pre class="fragment">  LOCAL_LDLIBS := -lGLESv1_CM
</pre><p>The '1.x' here refers to both versions 1.0 and 1.1 of the OpenGL ES APIs. Please note that:</p>
<ul>
<li>OpenGL ES 1.0 is supported on <em>all</em> Android-based devices.</li>
<li>OpenGL ES 1.1 is fully supported only on specific devices that have the corresponding GPU.</li>
</ul>
<p>This is because Android comes with a 1.0-capable software renderer that can be used on GPU-less devices.</p>
<p>Developers should query the OpenGL ES version string and extension string to know if the current device supports the features they need. See the description of glGetString() in the specification to see how to do that:</p>
<p><a href="http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml">http://www.khronos.org/opengles/sdk/1.1/docs/man/glGetString.xml</a></p>
<p>Additionally, developers must put a <code>&lt;uses-feature&gt;</code> tag in their manifest file to indicate which version of OpenGL ES their application requires. See the documentation linked below for details:</p>
<p><a href="http://developer.android.com/guide/topics/manifest/uses-feature-element.html">http://developer.android.com/guide/topics/manifest/uses-feature-element.html</a></p>
<p>Please note that EGL APIs are only available starting from API level 9. You can however perform the corresponding operations (surface creation and flipping) by using the VM. For example, with a GLSurfaceView as described here:</p>
<p><a href="http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html">http://android-developers.blogspot.com/2009/04/introducing-glsurfaceview.html</a></p>
<p>The "san-angeles" sample application shows how you can do that, while rendering each frame in native code. This is a small Android port of the excellent "San Angeles Observation" demo program. For more information about it, see:</p>
<p><a href="http://jet.ro/visuals/san-angeles-observation/">http://jet.ro/visuals/san-angeles-observation/</a></p>
<h2>Android-5 Stable Native APIs</h2>
<p>All the APIs listed below are available for developing native code that runs on Android 2.0 system images and above.</p>
<h3>The OpenGL ES 2.0 Library:</h3>
<p>The standard OpenGL ES 2.0 headers <code>&lt;GLES2/gl2.h&gt;</code> and <code>&lt;GLES2/gl2ext.h&gt;</code> contain the declarations needed to perform OpenGL ES 2.0 rendering calls from native code. This includes the ability to define and use vertex and fragment shaders using the GLSL language.</p>
<p>If you use them, your native module should link to /system/lib/libGLESv2.so as in: </p>
<pre class="fragment">  LOCAL_LDLIBS := -lGLESv2
</pre><p>Not all devices support OpenGL ES 2.0, developers should thus query the implementation's version and extension strings, and put a <code>&lt;uses-feature&gt;</code> tag in their Android manifest. See Section III above for details.</p>
<p>Please note that EGL APIs are only available starting from API level 9.</p>
<p>The "hello-gl2" sample application demonstrate this. It is used to draw a very simple triangle with the help of a vertex and fragment shaders.</p>
<p>IMPORTANT NOTE<br/>
 The Android emulator does not support OpenGL ES 2.0 hardware emulation at this time. Running and testing code that uses this API requires a real device with such capabilities.</p>
<h2>IV. Android-8 Stable Native APIs</h2>
<p>All the APIs listed below are available for developing native code that runs on Android 2.2 system images and above.</p>
<h3>The 'jnigraphics' Library:</h3>
<p>This is a tiny library that exposes a stable, C-based interface that allows native code to reliably access the pixel buffers of Java bitmap objects.</p>
<p>To use it, include the <code>&lt;android/bitmap.h&gt;</code> header in your source code, and and link to the jnigraphics library as in: </p>
<pre class="fragment">  LOCAL_LDLIBS += -ljnigraphics
</pre><p>For details, read the source header at the following location: </p>
<pre class="fragment">  platforms/android-8/arch-arm/usr/include/android/bitmap.h
</pre><p>Briefly, typical usage should look like:</p>
<ol type="1">
<li>Use <code>AndroidBitmap_getInfo()</code> to retrieve information about a given bitmap handle from JNI (e.g. its width/height/pixel format)</li>
<li>Use <code>AndroidBitmap_lockPixels()</code> to lock the pixel buffer and retrieve a pointer to it. This ensures the pixels will not move until <code>AndroidBitmap_unlockPixels()</code> is called.</li>
<li>Modify the pixel buffer, according to its pixel format, width, stride, etc.., in native code.</li>
<li>Call <code>AndroidBitmap_unlockPixels()</code> to unlock the buffer.</li>
</ol>
<h2>Android-9 Stable Native APIs</h2>
<p>All the APIs listed below are available for developing native code that runs on Android &gt; 2.3 system images and above.</p>
<h3>The EGL graphics library:</h3>
<p>EGL provides a native platform interface to allocate and manage OpenGLES surfaces. For more information about its features, please see:</p>
<p><a href="http://www.khronos.org/egl">http://www.khronos.org/egl</a></p>
<p>In a nutshell, this will allow you to do the following directly from native code:</p>
<ul>
<li>List supported EGL configurations</li>
<li>Allocate and release OpenGLES surfaces</li>
<li>Swap/Flip surfaces for display (eglSwapBuffers)</li>
</ul>
<p>This is provided through the following headers: </p>
<pre class="fragment">    &lt;EGL/egl.h&gt;        -&gt; Main EGL API definitions
    &lt;EGL/eglext.h&gt;     -&gt; EGL extension-related definitions
</pre><p>You cal link against the system's EGL library by adding the following to your NDK module definition: </p>
<pre class="fragment">    LOCAL_LDLIBS += -lEGL
</pre><h3>The OpenSL ES native audio Library:</h3>
<p>Android native audio is based on Khronos Group OpenSL ES&amp;#0153; 1.0.1.</p>
<p>The standard OpenSL ES headers <code>&lt;SLES/OpenSLES.h&gt;</code> and <code>&lt;SLES/OpenSLES_Platform.h&gt;</code> contain the declarations needed to perform audio input and output from the native side of Android.</p>
<p>NOTE: Despite the fact that the OpenSL ES 1.0.1 specification uses <code>&lt;OpenSLES.h&gt;</code> to include these headers, Khronos has modified later versions of the document to recommend <code>&lt;SLES/OpenSLES.h&gt;</code> instead, hence the later approach was adopted for Android.</p>
<p>This API level also provides Android-specific extensions, see the content of <code>&lt;SLES/OpenSLES_Android.h&gt;</code> and <code>&lt;SLES/OpenSLES_AndroidConfiguration.h&gt;</code> for details.</p>
<p>The system library named "libOpenSLES.so" implements the public native audio functions. Use the following to link your modules against it: </p>
<pre class="fragment">    LOCAL_LDLIBS += -lOpenSLES
</pre><p>For more information about this topic, please read the document docs/opensles/index.html.</p>
<h3>The Android native application APIs:</h3>
<p>Starting from API level 9, it is possible to entirely write an Android application with native code (i.e. without any Java). That does not mean that your code does not run inside a VM though, and most of the features of the platform will still need to be accessed through JNI.</p>
<p>For more information about this topic, please read the dedicated document named docs/NATIVE-ACTIVITY.html</p>
<p>The following headers correspond to these new native APIs (see comments inside them for more details):</p>
<ul>
<li><code>&lt;android/native_activity.h&gt;</code> Activity lifecycle management (and general entry point)</li>
<li><code>&lt;android/looper.h&gt;</code><br/>
 <code>&lt;android/input.h&gt;</code><br/>
 <code>&lt;android/keycodes.h&gt;</code><br/>
 <code>&lt;android/sensor.h&gt;</code> To Listen to input events and sensors directly from native code.</li>
<li><code>&lt;android/rect.h&gt;</code><br/>
 <code>&lt;android/window.h&gt;</code><br/>
 <code>&lt;android/native_window.h&gt;</code><br/>
 <code>&lt;android/native_window_jni.h&gt;</code> Window management, including the ability to lock/unlock the pixel buffer to draw directly into it.</li>
<li><code>&lt;android/configuration.h&gt;</code><br/>
 <code>&lt;android/asset_manager.h&gt;</code><br/>
 <code>&lt;android/storage_manager.h&gt;</code><br/>
 <code>&lt;android/obb.h&gt;</code><br/>
</li>
</ul>
<p>Direct (read-only) access to assets embedded in your .apk. or the Opaque Binary Blob (OBB) files, a new feature of Android X.X that allows one to distribute large amount of application data outside of the .apk (useful for game assets, for example).</p>
<p>All the corresponding functions are provided by the "libandroid.so" library version that comes with API level 9. To use it, use the following: </p>
<pre class="fragment">    LOCAL_LDLIBS += -landroid
</pre><h2>Android-14 Stable Native APIs</h2>
<p>All the APIs listed below are available for developing native code that runs on Android &gt; 4.0 system images and above.</p>
<h3>The OpenMAX AL native multimedia library:</h3>
<p>Android native multimedia is based on Khronos Group OpenMAX AL&amp;#0153; 1.0.1.</p>
<p>The standard OpenMAX AL headers <code>&lt;OMXAL/OpenMAXAL.h&gt;</code> and <code>&lt;OMXAL/OpenMAXAL_Platform.h&gt;</code> contain the declarations needed to perform multimedia output from the native side of Android.</p>
<p>NOTE<br/>
 Despite the fact that the OpenMAX AL 1.0.1 specification uses <code>&lt;OpenMAXAL.h&gt;</code> to include these headers, Khronos has modified later versions of the document to recommend <code>&lt;OMXAL/OpenMAXAL.h&gt;</code> instead, hence the later approach was adopted for Android.</p>
<p>This API level also provides Android-specific extensions, see the content of <code>&lt;OMXAL/OpenMAXAL_Android.h&gt;</code> for details.</p>
<p>The system library named "`libOpenMAXAL.so`" implements the public native multimedia functions. Use the following to link your modules against it: </p>
<pre class="fragment">    LOCAL_LDLIBS += -lOpenMAXAL
</pre><p>For more information about this topic, please read the document docs/openmaxal/index.html.</p>
<h3>The OpenSL ES native audio library:</h3>
<p>Native audio APIs based on OpenSL ES were added in API level 9. Starting with API level 14, the native audio API was extended to support decoding to PCM. See section "The OpenSL ES native audio Library" above for a high-level summary of how to use OpenSL ES, and the details in docs/opensles/index.html.</p>
<h2>Android-18 Stable Native APIs</h2>
<p>All the APIs listed below are available for developing native code that runs on Android 4.3 system images and above.</p>
<h3>The OpenGL ES 3.0 Library:</h3>
<p>The standard OpenGL ES 3.0 headers <code>&lt;GLES3/gl3.h&gt;</code> and <code>&lt;GLES3/gl3ext.h&gt;</code> contain the declarations needed to perform OpenGL ES 3.0 rendering calls from native code.</p>
<p>If you use them, your native module should link to /system/lib/libGLESv3.so as in:</p>
<p>LOCAL_LDLIBS := -lGLESv3</p>
<p>Not all devices support OpenGL ES 3.0, developers should thus query the implementation's version and extension strings, and put a <code>&lt;uses-feature&gt;</code> tag in their Android manifest. See Section III above for details.</p>
<p>The "gles3jni" sample application demonstrates this.</p>
<p>IMPORTANT NOTE: The Android emulator does not support OpenGL ES 3.0 hardware emulation at this time. Running and testing code that uses this API requires a real device with such capabilities. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Wed Jun 25 2014 00:51:19 for NDK Programmer&#39;s Guide by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.5 </li>
  </ul>
</div>
</body>
</html>
